Creating/Opening Databases

In-Memory Databases

In-memory databases are created in conventional or shared memory when the database open API is called. When the database is opened, memory devices are initialized and metadata, in the form of the database dictionary that informs the eXtremeDB runtime about the database structure, is loaded into memory.  The runtime is initialized with several user-specified parameters that determine runtime behavior until the database is closed. Then, before application termination, the database must be closed.

The APIs and structures for defining in-memory database parameters are specific to the programming language used. Please use the links below to view detailed explanations and examples for your development environment:

C	Opening and closing in-memory databases in C
C++	Opening and closing in-memory databases in C++
Java	Opening and closing in-memory databases in Java
Python	Opening and closing in-memory databases in Python
C#	Opening and closing in-memory databases in C#

Persistent Databases

Persistent databases are created (for the initial instance) or can be opened from an existing persistent <dbname>.dbs file when the database open API is called. After the database open, all database operations are performed with the same APIs as for in-memory databases. However, for persistent databases a number of additional considerations are important. The key factors are discussed in the following sections.

Memory Devices

Whereas for in-memory databases a single memory device contains all database data and metadata, persistent databases require a minimum of four memory devices for the distinct memory regions described in the Database Storage page: data, metadata, cache and log.

Memory page size

The MemPageSize can be calculated to optimize performance and will vary depending on the application dynamics, but as a rule of thumb, page size should be between 80 and 512 bytes; a 128 byte page size is good in most situations. (Note that rtree indexes require larger page sizes. If error code MCO_ERR_RTREE is encountered during database transactions, increase the page size in increments until these error codes are remedied.)

Disk page size

For persistent and hybrid databases both parameters should be set to a power of 2 with DiskPageSize being at least 8 times the MemPageSize value to allow for efficient caching. It may be useful to map the DiskPageSize to the blocking factor of the persistent media. This is because eXtremeDB performs I/O in units of DiskPageSize (i.e. if you modify a record on a page that holds five records, the runtime will write the entire page), and disks perform I/O in blocks, regardless of the size of I/O requested by the database system. In other words, if the disk blocking factor is 8192 bytes, the disk will always read or write 8192 bytes, even if eXtremeDB makes a call to write 4096 bytes because its DiskPageSize is 4096 bytes. Given that the disk will always read or write 8192 bytes, eXtremeDB should, also.

When a persistent device is defined and the application does not explicitly assign the database page size for it, the runtime will assign it the default value of 4096 bytes. If multiple applications or tasks attempt to assign different persistent database page sizes for the same database, the runtime returns an error code.

Max Connections

For persistent as for in-memory databases, the MaxConnections parameter determines the maximum number of application connections possible for this database.

Disk Max Database Size

The MaxDiskDatabaseSize element specifies the maximum amount of persistent media space consumed. The database run-time will report MCO_E_DISK_SPACE_EXHAUSTED or MCO_ERR_DISK_SPACE_EXHAUSTED to the transaction that causes this threshold to be exceeded (depending on whether the release or debug libraries, respectively are linked in).

Log type

Transaction log files for persistent databases are created to provide automatic database recovery in the case of system failure. The transaction log file strategy is configurable to allow developers to choose the type most appropriate for the application and can have a significant impact on performance (see the Persistent Database I/O page for a more detailed discussion). The LogType specifies the logging strategy the runtime will use: NoLog, UndoLog or RedoLog. The LogType value is set to RedoLog by default.

The APIs and structures for defining database parameters are specific to the programming language used. Please use the links below to view detailed explanations and examples for your development environment:

C	Creating persistent databases in C
C++	Creating persistent databases in C++
Java	Creating persistent databases in Java
C#	Creating persistent databases in C#
Python	Creating persistent databases in Python